home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat5 / stdarg.z / stdarg
Encoding:
Text File  |  2002-10-03  |  7.0 KB  |  131 lines
  1.  
  2.  
  3.  
  4. ssssttttddddaaaarrrrgggg((((5555))))                                                            ssssttttddddaaaarrrrgggg((((5555))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      stdarg - variable argument list
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddaaaarrrrgggg....hhhh>>>>
  13.      vvvvooooiiiidddd vvvvaaaa____ssssttttaaaarrrrtttt ((((vvvvaaaa____lllliiiisssstttt aaaapppp,,,, _P_a_r_m_N))));;;;
  14.      _t_y_p_e vvvvaaaa____aaaarrrrgggg ((((vvvvaaaa____lllliiiisssstttt aaaapppp,,,, _t_y_p_e))));;;;
  15.      vvvvooooiiiidddd vvvvaaaa____eeeennnndddd ((((vvvvaaaa____lllliiiisssstttt aaaapppp))));;;;
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      This set of macros provides a means of writing portable procedures that
  19.      accept variable argument lists.  Routines having variable argument lists
  20.      (such as _p_r_i_n_t_f(3)) that do not use stdarg are inherently nonportable,
  21.      since different machines use different argument passing conventions.  The
  22.      stdarg facility is similar to _v_a_r_a_r_g_s(5), but is based on the ANSI
  23.      Standard for C.
  24.  
  25.      A variable argument list contains one or more parameters.  The rightmost
  26.      parameter plays a special role, and is designated _P_a_r_m_N in this
  27.      discussion.
  28.  
  29.      _v_a__l_i_s_t is a type suitable for storing information needed by the macros
  30.      vvvvaaaa____ssssttttaaaarrrrtttt, vvvvaaaa____aaaarrrrgggg, and vvvvaaaa____eeeennnndddd.  The called function must declare a
  31.      variable (referred to as _a_p) of type _v_a__l_i_s_t, used to access the argument
  32.      list.
  33.  
  34.      The vvvvaaaa____ssssttttaaaarrrrtttt ((((aaaapppp,,,, _P_a_r_m_N) macro initializes _a_p for subsequent use by
  35.      vvvvaaaa____aaaarrrrgggg and vvvvaaaa____eeeennnndddd.  vvvvaaaa____ssssttttaaaarrrrtttt must be called before any use of vvvvaaaa____aaaarrrrgggg.
  36.      The ANSI C Standard (ANSI X3.159-1989) restricts the type of _p_a_r_m_N to one
  37.      of the types resulting from the _d_e_f_a_u_l_t _a_r_g_u_m_e_n_t _p_r_o_m_o_t_i_o_n_s, currently
  38.      iiiinnnntttt, uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt, pointer, or ddddoooouuuubbbblllleeee.  If vvvvaaaa____ssssttttaaaarrrrtttt is invoked with a
  39.      _p_a_r_m_N which is not one of these types (e.g., if _p_a_r_m_N is sssshhhhoooorrrrtttt or cccchhhhaaaarrrr)
  40.      the behavior is undefined.
  41.  
  42.      The vvvvaaaa____aaaarrrrgggg ((((aaaapppp,,,, _t_y_p_e) macro will return the next argument in the list
  43.      pointed to by _a_p.  The first invocation of vvvvaaaa____aaaarrrrgggg returns the value of
  44.      the argument after that specified by _P_a_r_m_N.  Successive invocations
  45.      return the values of the remaining arguments in succession.  _t_y_p_e is the
  46.      type to which the expected argument will be converted when passed as an
  47.      argument, as indicated by the _d_e_f_a_u_l_t _a_r_g_u_m_e_n_t _p_r_o_m_o_t_i_o_n_s.  Thus,
  48.      arguments that are cccchhhhaaaarrrr or sssshhhhoooorrrrtttt should be accessed as iiiinnnntttt; uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr
  49.      or uuuunnnnssssiiiiggggnnnneeeedddd sssshhhhoooorrrrtttt should be accessed as uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt; and ffffllllooooaaaatttt arguments
  50.      should be accessed as ddddoooouuuubbbblllleeee.  Arguments which are pointers should be
  51.      accessed using their own type.  Different types can be mixed, but it is
  52.      up to the routine to know what type of argument is expected.
  53.  
  54.      vvvvaaaa____eeeennnndddd ((((aaaapppp)))) is used to finish up.
  55.  
  56.  
  57.  
  59.  
  60.  
  61.                                                                         PPPPaaaaggggeeee 1111
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68. ssssttttddddaaaarrrrgggg((((5555))))                                                            ssssttttddddaaaarrrrgggg((((5555))))
  69.  
  70.  
  71.  
  72.      Multiple traversals, each bracketed by vvvvaaaa____ssssttttaaaarrrrtttt ...  vvvvaaaa____eeeennnndddd,,,, are
  73.      possible.
  74.  
  75. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  76.      #include <stdarg.h>
  77.      #define MAXARGS 31
  78.      void f1(int nptrs, ...)
  79.      {
  80.              va_list ap;
  81.              char *array[MAXARGS];
  82.              int ptr_no = 0;
  83.              if (nptrs > MAXARGS)
  84.                      nptrs = MAXARGS;
  85.              va_start(ap, nptrs);
  86.              while (ptr_no < nptrs)
  87.                      (array[ptr_no++] = va_arg(ap, char *));
  88.              va_end(ap);
  89.      }
  90.  
  91. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  92.      varargs(5)
  93.  
  94. BBBBUUUUGGGGSSSS
  95.      Due to the procedure calling convention on the MIPS processor, floating-
  96.      point parameters may be inaccessible via _s_t_d_a_r_g unless they appear _a_f_t_e_r
  97.      a parameter of non-floating-point type.  Thus, in the code sequence
  98.      extern int foo(float,...);
  99.      foo(1.0,2.0);
  100.      the parameter _2._0 may be accessed incorrectly.  If the function expected
  101.      an intervening non-floating-point parameter, such as
  102.      extern int foo(float,...);
  103.      foo(1.0,4,2.0);
  104.      the second floating-point parameter would be accessible as a _d_o_u_b_l_e.  No
  105.      problem is encountered, of course, if the type of the first argument is
  106.      not floating-point.
  107.  
  108.      _S_t_d_a_r_g cannot be used when passing structures as parameters, as it is
  109.      impossible to determine their alignment at runtime.
  110.  
  111.      It is up to the calling routine to determine how many arguments there
  112.      are, since it is not possible to determine this from the stack frame.
  113.      For example, _e_x_e_c_l passes a 0 to signal the end of the list.  _P_r_i_n_t_f can
  114.      tell how many arguments are supposed to be there by the format.
  115.  
  116.      The macros _v_a__s_t_a_r_t and _v_a__e_n_d may be arbitrarily complex; for example,
  117.      _v_a__s_t_a_r_t might contain an opening brace, which is closed by a matching
  118.      brace in _v_a__e_n_d.  Thus, they should only be used where they could be
  119.      placed within a single complex statement.
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.